home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / g_man / cat3 / OpenGL / glstencilfunc.z / glstencilfunc
Encoding:
Text File  |  2001-04-17  |  8.4 KB  |  136 lines
  1.  
  2.  
  3.  
  4. ggggllllSSSStttteeeennnncccciiiillllFFFFuuuunnnncccc((((3333GGGG))))              OOOOppppeeeennnnGGGGLLLL RRRReeeeffffeeeerrrreeeennnncccceeee              ggggllllSSSStttteeeennnncccciiiillllFFFFuuuunnnncccc((((3333GGGG))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ggggllllSSSStttteeeennnncccciiiillllFFFFuuuunnnncccc - set function and reference value for stencil testing
  10.  
  11.  
  12. CCCC SSSSPPPPEEEECCCCIIIIFFFFIIIICCCCAAAATTTTIIIIOOOONNNN
  13.      void ggggllllSSSStttteeeennnncccciiiillllFFFFuuuunnnncccc( GLenum _f_u_n_c,
  14.                          GLint _r_e_f,
  15.                          GLuint _m_a_s_k )
  16.  
  17.  
  18. PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS
  19.      _f_u_n_c  Specifies the test function.  Eight tokens are valid:  GGGGLLLL____NNNNEEEEVVVVEEEERRRR,
  20.            GGGGLLLL____LLLLEEEESSSSSSSS, GGGGLLLL____LLLLEEEEQQQQUUUUAAAALLLL, GGGGLLLL____GGGGRRRREEEEAAAATTTTEEEERRRR, GGGGLLLL____GGGGEEEEQQQQUUUUAAAALLLL, GGGGLLLL____EEEEQQQQUUUUAAAALLLL, GGGGLLLL____NNNNOOOOTTTTEEEEQQQQUUUUAAAALLLL,
  21.            and GGGGLLLL____AAAALLLLWWWWAAAAYYYYSSSS. The initial value is GGGGLLLL____AAAALLLLWWWWAAAAYYYYSSSS.
  22.  
  23.      _r_e_f   Specifies the reference value for the stencil test.  _r_e_f is clamped
  24.                             n
  25.            to the range [0,2 -1], where n is the number of bitplanes in the
  26.            stencil buffer. The initial value is 0.
  27.  
  28.      _m_a_s_k  Specifies a mask that is ANDed with both the reference value and
  29.            the stored stencil value when the test is done. The initial value
  30.            is all 1's.
  31.  
  32. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  33.      Stenciling, like depth-buffering, enables and disables drawing on a per-
  34.      pixel basis.  You draw into the stencil planes using GL drawing
  35.      primitives, then render geometry and images, using the stencil planes to
  36.      mask out portions of the screen.  Stenciling is typically used in
  37.      multipass rendering algorithms to achieve special effects, such as
  38.      decals, outlining, and constructive solid geometry rendering.
  39.  
  40.      The stencil test conditionally eliminates a pixel based on the outcome of
  41.      a comparison between the reference value and the value in the stencil
  42.      buffer.  To enable and disable the test, call ggggllllEEEEnnnnaaaabbbblllleeee and ggggllllDDDDiiiissssaaaabbbblllleeee with
  43.      argument GGGGLLLL____SSSSTTTTEEEENNNNCCCCIIIILLLL____TTTTEEEESSSSTTTT.  To specify actions based on the outcome of the
  44.      stencil test, call ggggllllSSSStttteeeennnncccciiiillllOOOOpppp.
  45.  
  46.      _f_u_n_c is a symbolic constant that determines the stencil comparison
  47.      function.  It accepts one of eight values, shown in the following list.
  48.      _r_e_f is an integer reference value that is used in the stencil comparison.
  49.                                     n
  50.      It is clamped to the range [0,2 -1], where n is the number of bitplanes
  51.      in the stencil buffer.  _m_a_s_k is bitwise ANDed with both the reference
  52.      value and the stored stencil value, with the ANDed values participating
  53.      in the comparison.
  54.  
  55.      If _s_t_e_n_c_i_l represents the value stored in the corresponding stencil
  56.      buffer location, the following list shows the effect of each comparison
  57.      function that can be specified by _f_u_n_c.  Only if the comparison succeeds
  58.      is the pixel passed through to the next stage in the rasterization
  59.      process (see ggggllllSSSStttteeeennnncccciiiillllOOOOpppp).  All tests treat _s_t_e_n_c_i_l values as unsigned
  60.                                n
  61.      integers in the range [0,2 -1], where n is the number of bitplanes in the
  62.      stencil buffer.
  63.  
  64.  
  65.  
  66.                                                                         PPPPaaaaggggeeee 1111
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73. ggggllllSSSStttteeeennnncccciiiillllFFFFuuuunnnncccc((((3333GGGG))))              OOOOppppeeeennnnGGGGLLLL RRRReeeeffffeeeerrrreeeennnncccceeee              ggggllllSSSStttteeeennnncccciiiillllFFFFuuuunnnncccc((((3333GGGG))))
  74.  
  75.  
  76.  
  77.      The following values are accepted by _f_u_n_c:
  78.  
  79.      GGGGLLLL____NNNNEEEEVVVVEEEERRRR          Always fails.
  80.  
  81.      GGGGLLLL____LLLLEEEESSSSSSSS           Passes if ( _r_e_f & _m_a_s_k ) < ( _s_t_e_n_c_i_l & _m_a_s_k ).
  82.  
  83.      GGGGLLLL____LLLLEEEEQQQQUUUUAAAALLLL         Passes if ( _r_e_f & _m_a_s_k ) _< ( _s_t_e_n_c_i_l & _m_a_s_k ).
  84.  
  85.      GGGGLLLL____GGGGRRRREEEEAAAATTTTEEEERRRR        Passes if ( _r_e_f & _m_a_s_k ) > ( _s_t_e_n_c_i_l & _m_a_s_k ).
  86.  
  87.      GGGGLLLL____GGGGEEEEQQQQUUUUAAAALLLL         Passes if ( _r_e_f & _m_a_s_k ) _> ( _s_t_e_n_c_i_l & _m_a_s_k ).
  88.  
  89.      GGGGLLLL____EEEEQQQQUUUUAAAALLLL          Passes if ( _r_e_f & _m_a_s_k ) = ( _s_t_e_n_c_i_l & _m_a_s_k ).
  90.  
  91.      GGGGLLLL____NNNNOOOOTTTTEEEEQQQQUUUUAAAALLLL       Passes if ( _r_e_f & _m_a_s_k ) =/  ( _s_t_e_n_c_i_l & _m_a_s_k ).
  92.  
  93.      GGGGLLLL____AAAALLLLWWWWAAAAYYYYSSSS         Always passes.
  94.  
  95. NNNNOOOOTTTTEEEESSSS
  96.      Initially, the stencil test is disabled.  If there is no stencil buffer,
  97.      no stencil modification can occur and it is as if the stencil test always
  98.      passes.
  99.  
  100. EEEERRRRRRRROOOORRRRSSSS
  101.      GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____EEEENNNNUUUUMMMM is generated if _f_u_n_c is not one of the eight accepted
  102.      values.
  103.  
  104.      GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN is generated if ggggllllSSSStttteeeennnncccciiiillllFFFFuuuunnnncccc is executed between
  105.      the execution of ggggllllBBBBeeeeggggiiiinnnn and the corresponding execution of ggggllllEEEEnnnndddd.
  106.  
  107. AAAASSSSSSSSOOOOCCCCIIIIAAAATTTTEEEEDDDD GGGGEEEETTTTSSSS
  108.      ggggllllGGGGeeeetttt with argument GGGGLLLL____SSSSTTTTEEEENNNNCCCCIIIILLLL____FFFFUUUUNNNNCCCC
  109.      ggggllllGGGGeeeetttt with argument GGGGLLLL____SSSSTTTTEEEENNNNCCCCIIIILLLL____VVVVAAAALLLLUUUUEEEE____MMMMAAAASSSSKKKK
  110.      ggggllllGGGGeeeetttt with argument GGGGLLLL____SSSSTTTTEEEENNNNCCCCIIIILLLL____RRRREEEEFFFF
  111.      ggggllllGGGGeeeetttt with argument GGGGLLLL____SSSSTTTTEEEENNNNCCCCIIIILLLL____BBBBIIIITTTTSSSS
  112.      ggggllllIIIIssssEEEEnnnnaaaabbbblllleeeedddd with argument GGGGLLLL____SSSSTTTTEEEENNNNCCCCIIIILLLL____TTTTEEEESSSSTTTT
  113.  
  114.  
  115. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  116.      ggggllllAAAAllllpppphhhhaaaaFFFFuuuunnnncccc, ggggllllBBBBlllleeeennnnddddFFFFuuuunnnncccc, ggggllllDDDDeeeepppptttthhhhFFFFuuuunnnncccc, ggggllllEEEEnnnnaaaabbbblllleeee, ggggllllIIIIssssEEEEnnnnaaaabbbblllleeeedddd, ggggllllLLLLooooggggiiiiccccOOOOpppp,
  117.      ggggllllSSSStttteeeennnncccciiiillllOOOOpppp
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.                                                                         PPPPaaaaggggeeee 2222
  133.  
  134.  
  135.  
  136.